//! # 观测性核心接口定义
//! 
//! 定义观测性管理的核心trait接口，采用面向接口编程设计。
//! 支持指标收集、分布式追踪、日志记录的统一抽象。

use rustcloud_core::{ServiceResult, ServiceError};
use rustcloud_metrics::{MetricsCollector, MetricType, Labels};
use std::sync::Arc;
use std::collections::HashMap;
use async_trait::async_trait;
use super::context::ObservabilityContext;

/// 日志级别枚举
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LogLevel {
    Trace,
    Debug,
    Info,
    Warn,
    Error,
}

/// 观测性管理器核心接口
/// 
/// 定义了统一观测性管理的核心操作，支持上下文管理、指标收集、
/// 追踪和日志记录的统一接口。
#[async_trait]
pub trait ObservabilityManager: Send + Sync {
    /// 启动观测性上下文
    /// 
    /// 创建新的观测性上下文，开始记录相关的指标、追踪和日志。
    /// 
    /// # 参数
    /// * `service_name` - 服务名称
    /// * `operation_name` - 操作名称
    /// 
    /// # 返回值
    /// 返回上下文ID，用于后续操作关联
    async fn start_context(&self, service_name: String, operation_name: String) -> ServiceResult<String>;
    
    /// 结束观测性上下文
    /// 
    /// # 参数
    /// * `context_id` - 上下文ID
    async fn end_context(&self, context_id: &str) -> ServiceResult<()>;
    
    /// 记录错误信息
    /// 
    /// # 参数
    /// * `context_id` - 上下文ID
    /// * `error` - 错误信息
    async fn record_error(&self, context_id: &str, error: &str) -> ServiceResult<()>;
    
    /// 添加上下文属性
    /// 
    /// # 参数
    /// * `context_id` - 上下文ID
    /// * `key` - 属性键
    /// * `value` - 属性值
    async fn add_context_attribute(&self, context_id: &str, key: String, value: serde_json::Value) -> ServiceResult<()>;
    
    /// 记录计数器指标
    /// 
    /// # 参数
    /// * `name` - 指标名称
    /// * `value` - 指标值
    /// * `labels` - 标签
    async fn record_counter(&self, name: &str, value: f64, labels: Labels) -> ServiceResult<()>;
    
    /// 记录仪表盘指标
    /// 
    /// # 参数
    /// * `name` - 指标名称
    /// * `value` - 指标值
    /// * `labels` - 标签
    async fn record_gauge(&self, name: &str, value: f64, labels: Labels) -> ServiceResult<()>;
    
    /// 记录直方图指标
    /// 
    /// # 参数
    /// * `name` - 指标名称
    /// * `value` - 指标值
    /// * `labels` - 标签
    async fn record_histogram(&self, name: &str, value: f64, labels: Labels) -> ServiceResult<()>;
    
    /// 记录日志
    /// 
    /// # 参数
    /// * `level` - 日志级别
    /// * `message` - 日志消息
    /// * `context` - 观测性上下文（可选）
    async fn log(&self, level: LogLevel, message: &str, context: Option<&ObservabilityContext>) -> ServiceResult<()>;
}

/// 追踪处理器接口
/// 
/// 定义了分布式追踪的核心操作，支持span管理和事件记录。
#[async_trait]
pub trait TracingProcessor: Send + Sync {
    /// 开始Span
    /// 
    /// # 参数
    /// * `context` - 观测性上下文
    async fn start_span(&self, context: &ObservabilityContext) -> ServiceResult<()>;
    
    /// 结束Span
    /// 
    /// # 参数
    /// * `context` - 观测性上下文
    async fn end_span(&self, context: &ObservabilityContext) -> ServiceResult<()>;
    
    /// 添加事件
    /// 
    /// # 参数
    /// * `context` - 观测性上下文
    /// * `name` - 事件名称
    /// * `attributes` - 事件属性
    async fn add_event(&self, context: &ObservabilityContext, name: &str, attributes: HashMap<String, serde_json::Value>) -> ServiceResult<()>;
    
    /// 导出追踪数据
    async fn export(&self) -> ServiceResult<()>;
    
    /// 获取处理器名称
    fn name(&self) -> &str;
    
    /// 检查是否启用
    fn is_enabled(&self) -> bool;
}

/// 日志管理器接口
/// 
/// 定义了日志管理的核心操作，支持结构化日志和上下文关联。
#[async_trait]
pub trait LogManager: Send + Sync {
    /// 记录日志
    /// 
    /// # 参数
    /// * `level` - 日志级别
    /// * `message` - 日志消息
    /// * `context` - 观测性上下文（可选）
    async fn log(&self, level: LogLevel, message: &str, context: Option<&ObservabilityContext>) -> ServiceResult<()>;
    
    /// 记录结构化日志
    /// 
    /// # 参数
    /// * `level` - 日志级别
    /// * `message` - 日志消息
    /// * `fields` - 结构化字段
    /// * `context` - 观测性上下文（可选）
    async fn log_structured(&self, level: LogLevel, message: &str, fields: HashMap<String, serde_json::Value>, context: Option<&ObservabilityContext>) -> ServiceResult<()>;
    
    /// 导出日志
    async fn export(&self) -> ServiceResult<()>;
    
    /// 获取管理器名称
    fn name(&self) -> &str;
    
    /// 检查是否启用
    fn is_enabled(&self) -> bool;
    
    /// 设置日志级别过滤
    fn set_level_filter(&mut self, level: LogLevel);
}

/// 指标收集器接口扩展
/// 
/// 为观测性管理提供额外的指标收集功能
#[async_trait]
pub trait ObservabilityMetricsCollector: Send + Sync {
    /// 记录业务指标
    /// 
    /// # 参数
    /// * `metric_name` - 指标名称
    /// * `value` - 指标值
    /// * `labels` - 标签
    /// * `context` - 观测性上下文（可选）
    async fn record_business_metric(&self, metric_name: &str, value: f64, labels: Labels, context: Option<&ObservabilityContext>) -> ServiceResult<()>;
    
    /// 记录性能指标
    /// 
    /// # 参数
    /// * `operation` - 操作名称
    /// * `duration_ms` - 持续时间（毫秒）
    /// * `context` - 观测性上下文（可选）
    async fn record_performance_metric(&self, operation: &str, duration_ms: f64, context: Option<&ObservabilityContext>) -> ServiceResult<()>;
    
    /// 记录错误指标
    /// 
    /// # 参数
    /// * `error_type` - 错误类型
    /// * `context` - 观测性上下文（可选）
    async fn record_error_metric(&self, error_type: &str, context: Option<&ObservabilityContext>) -> ServiceResult<()>;
    
    /// 获取收集器名称
    fn name(&self) -> &str;
    
    /// 检查是否启用
    fn is_enabled(&self) -> bool;
}